비밀번호, API Key, 인증서 등 비밀(Secrets) 키 관리하기

HandStack KVS 인증 및 인가 방식 (1/2)

이 구현은 HTTP 헤더를 등록 정보와 비교합니다. 헤더 값은 호출자가 조작할 수 있으므로, 그 자체를 강한 신원 증명으로 신뢰하지 않습니다.

• API 요청 시 특정 헤더 값을 서버로 전송합니다.
  • HandStack-MachineID: 클라이언트 하드웨어 고유 ID
  • HandStack-IP: 클라이언트 IP 주소
  • HandStack-HostName: 클라이언트 호스트 이름
  • HandStack-Environment: 실행 환경 (e.g., Development, Production)

HandStack KVS 인증 및 인가 방식 (2/2)

• 서버는 수신된 헤더 값을 handstack-secrets.json 파일의 등록 정보와 비교하여 요청을 처리합니다.

데이터 저장 구조: handstack-secrets.json (1/2)

이 예제의 비밀 데이터는 ack 서버의 handstack-secrets.json에 저장됩니다. 파일·백업 접근을 제한하고 TLS와 별도 인증·네트워크 통제를 적용합니다. 전문 비밀 저장소의 보호 기능과 동일하다고 가정하지 않습니다.

{
    "ManagementHost": { ... },
    "Secrets": { ... }
}

데이터 저장 구조: handstack-secrets.json (2/2)

• ManagementHost

  • 비밀 키를 관리(등록, 삭제)할 수 있는 관리자 클라이언트 정보를 정의합니다.

• Secrets

  • 각 클라이언트의 요청 조건과 일치하는 비밀 키 정보를 관리합니다.

handstack-secrets.json 상세 구조 (1/2)

{
    "ManagementHost": {
        "MachineID": "[Current Hardware ID]",
        "IpAddress": "[IP 주소]",
        "HostName": "[HostName]",
        "SystemVaultKey": "[Strong@Passw0rd]"
    },
    "Secrets": {
        "HandStack-MachineID|HandStack-IP|HandStack-HostName": [
            { "Key": "DbPassword", "Value": "[AES256 Base64]", "IsEncryption": "Y", ... },
            { "Key": "ApiToken", "Value": "[Plain Text]", "IsEncryption": "N", ... }
        ]
    }
}

handstack-secrets.json 상세 구조 (2/2)

• Secrets의 키는 MachineID, IP, HostName을 |로 조합하여 사용하며, 이 값과 일치하는 클라이언트만 접근할 수 있습니다.

KVS RESTFul API 소개 (1/2)

서버 애플리케이션·CLI에서 사용하는 관리·수급 API입니다. 아래 localhost·예제 키는 실습용이며 운영 값으로 재사용하지 않습니다.

• 키 목록 API GET /secrets

  • 수급 가능한 전체 키 목록을 조회합니다.

• 키 등록 API POST /secrets

  • 새로운 키를 등록하거나 기존 키를 변경합니다.

• 키 삭제 API DELETE /secrets/{name}

  • 등록된 키를 삭제합니다.

KVS RESTFul API 소개 (2/2)

• 키 수급 API GET /secrets/{name}
  • 특정 키의 값을 가져옵니다.

키 등록 API: POST /secrets (1/2)

관리자 조건을 확인한 뒤 등록합니다. 같은 이름은 덮어쓰므로 대상 환경·키 이름과 교체 후 의존 서비스의 동작을 먼저 확인합니다.

• 요청 예제

키 등록 API: POST /secrets (2/2)

curl --location 'http://localhost:8421/secrets' \
--header 'HandStack-MachineID: [Current Hardware ID]' \
--header 'HandStack-IP: [LocalIP]' \
--header 'HandStack-HostName: [HostName]' \
--header 'HandStack-Environment: [EnvironmentName]' \
--header 'Content-Type: application/json' \
--data '{
    "Key": "PlainValue",
    "Value": "Hello World Blabla",
    "IsEncryption": "N",
    "ExpiresAt": null,
    "Environment": "Development",
    "Tags": ["Test"]
}'

애플리케이션 적용 예제 (C#) (1/4)

ASP.NET Core 애플리케이션에서 HttpClient를 사용하여 ack 서버로부터 비밀 키를 가져오는 예제입니다.

애플리케이션 적용 예제 (C#) (2/4)

// http://localhost:8421/wwwroot/api/index/get-secret?keyName=MySecret
[HttpGet("[action]")]
public async Task<string> GetSecret(string? baseUrl, string keyName)
{
    if (string.IsNullOrEmpty(baseUrl) == true)
    {
        baseUrl = Request.GetBaseUrl();
    }

    var requestUri = $"{baseUrl}/secrets/{keyName}";
    using var httpClient = new HttpClient() { Timeout = TimeSpan.FromSeconds(3) };
    using var request = new HttpRequestMessage(HttpMethod.Get, requestUri);

    // KVS 서버에 전달할 클라이언트 식별 헤더 추가

애플리케이션 적용 예제 (C#) (3/4)

    request.Headers.Add("HandStack-MachineID", GlobalConfiguration.HardwareID);
    request.Headers.Add("HandStack-IP", GlobalConfiguration.ServerLocalIP);
    request.Headers.Add("HandStack-HostName", GlobalConfiguration.HostName);
    request.Headers.Add("HandStack-Environment", GlobalConfiguration.RunningEnvironment);

    using var response = await httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();

    var secretData = await response.Content.ReadAsStringAsync();
    var keyItem = JsonConvert.DeserializeObject<KeyItem>(secretData)!;

    // IsEncryption이 'Y'인 경우, 복호화하여 원본 값 반환
    string systemVaultKey = "[Strong@Passw0rd]"; // 실제로는 안전한 곳에서 로드
    var vaultKey = (systemVaultKey + "|" + keyItem.Key.PadRight(32, '0')).Substring(0, 32);

애플리케이션 적용 예제 (C#) (4/4)

    var content = keyItem.IsEncryption.ToBoolean() == true ?
        keyItem.Value.DecryptAES(vaultKey) : keyItem.Value;

    return content;
}